docs(patterns): on-chain / off-chain boundary guide + feat(design-system): shared versioned tokens package - #289

Closes #251
Part of #260

Updated per review: build output is no longer committed, and the showcase integration has moved to its own PR. The commits are still split one per issue.

Changes since the first round

One consequence worth calling out

build.js --check used to diff the committed dist/ against a fresh build. With nothing committed to diff, that check would be vacuous in a clean clone, so it now guards the drift that actually remains: tokens.json against docs/BRAND.md, which is the declared source of truth and the one pair nothing else stops being edited apart.

$ node build.js --check
Token source does not match docs/BRAND.md:
  - radius-md is 8px in docs/BRAND.md but 9px in tokens.json

BRAND.md is the source of truth. Update it first, then mirror it in tokens.json.

Verified it catches both a changed color and a changed scale value, and passes on a clean tree with no dist/ present.

1. On-chain / off-chain boundary guide (#251)

Unchanged from the first round. New docs/ONCHAIN_OFFCHAIN_BOUNDARY.md, the filename recommended in docs/strategy/04-onchain-gaming-research.md problem #1.

A five-question framework for placing one piece of game state or logic at a time, then three worked examples written against the current source rather than an idealized version:

Per the definition of done, the guide names the shortcuts the source review turned up rather than writing around them: battleship verifies a revealed cell against the commitment but never checks the committed board is a legal fleet, and snake has no require_auth anywhere in src/ and derives food placement from the tick counter. It also states plainly what Soroban throughput cannot support, and cross-links PERFORMANCE.md and PRIVACY_MODEL.md rather than restating them.

The definition of done asks for publication in the docs site's Learn section linked from the tutorial's next steps. The scaffold (#249) and tutorial (#250) have not landed, so the guide sits in docs/ and is linked from the README documentation list, the PATTERNS.md problem table, and a new Related section in PERFORMANCE.md. It slots into Learn unchanged when #249 lands.

2. Shared, versioned tokens package (Part of #260)

packages/tokens (cougr-tokens v1.0.0) encodes every value in docs/BRAND.md: four neutrals, primary and accent, three maturity-tier colors, two font stacks, the eight-step spacing scale, four radii, and the four fixed logo tones. Verified mechanically that nothing in BRAND.md is missing and no color was invented.

Format decision. tokens.json is the single hand-edited source; a zero-dependency build.js emits both dist/tokens.css and dist/tokens.js. CSS custom properties alone are preferable unless there is a build-time transform need, and there is one: anything producing a standalone artifact (an SVG, a PNG, terminal output) is consumed outside a document, so custom properties declared by a host page never resolve. Both outputs come from the same build and cannot disagree.

Style Dictionary was considered and skipped: it would add a dependency and a toolchain to a repository whose only other Node tool is deliberately install-free, for a transform that is about forty lines.

Theming. Light and dark are complete for every themed token. Light is the default on :root, dark applies under prefers-color-scheme unless the document opts out with data-theme="light", and an explicit data-theme on the root element always wins.

Versioning. Semver against the token surface rather than the code, with bump rules and the change procedure in the package README and a CHANGELOG.md. Each consumer pins its own range, so one can upgrade ahead of the other and the divergence is a fact in a lockfile rather than something noticed by eye.

docs/BRAND.md had a line saying a code package was out of scope and tracked separately; it now points at the package and restates that BRAND.md remains the source of truth.

Why this says "Part of #260" rather than "Closes"

#260's definition of done has two items. This PR ships the first (a versioned package with light and dark values for every token). The second is "at least one real site/build consumes it and visibly reflects a token change when the package is updated" — that was what the tools/preview-gen integration was doing here, since the docs-site scaffold (#249) hasn't landed and the showcase generator was the only real consumer available.

Splitting it out is fine, but it does mean #260 shouldn't auto-close on this PR with its second item outstanding. So the follow-up carries Closes #260, and this one carries Part of #260. Say the word if you'd rather this PR close it and the follow-up just reference it.

Follow-up PR

The showcase integration is now #291, stacked on this branch. It converts the four preview renderers from their hand-copied slate palettes to the shared tokens and includes the regenerated previews, which is the end-to-end proof for #260's second item. It also handles the consequence of un-committing dist/: generate.js builds the tokens on first run, so node generate.js <game> still works from a fresh clone with no setup step.

It is stacked, so it will show only its own diff once this merges. Happy to reorder if you'd rather review them the other way round.

Validation

• node build.js and node build.js --check, both clean, including --check on a tree with no dist/ present.
• Negative-tested the drift check by changing a color and a scale value in tokens.json: both fail with a specific message, and pass again when reverted.
• Ran each step of the new workflow locally, including the module load assertion and the "dist is not tracked" guard.
• Cross-checked every hex and scale value in docs/BRAND.md against tokens.json: none missing, none added.
• All relative links in the new and edited Markdown resolve.
• cargo fmt --check clean. No Rust source is touched, so Core CI's path filter does not select this PR.

On the rebase

main is still at be4f2f2 ("feat(cli): implement 'cougr new' project generator", 2026-07-27), and this branch was already based directly on it, so there was nothing to rebase onto. I re-fetched and confirmed against the API rather than assume. The force-push above is the restructuring, not a rebase. If you were expecting newer commits on main, something may not have landed yet, and I'll rebase as soon as it does.

Notes for review

• No changes to any example's code, per the documentation-only scope of docs(patterns): write the on-chain / off-chain boundary guide #251.
• I did not update the status rows in docs/strategy/12-documentation-architecture.md that still mark the boundary guide and design tokens as gaps. Those read as point-in-time analysis documents, so I left them alone; happy to update them if you would rather they track shipped state.